Skip to content

feat: durable approval plans, events and traceable run errors - #7

Merged
mukezhz merged 3 commits into
mainfrom
feat/durable-plans
Nov 16, 2026
Merged

mukezhz merged 3 commits into
mainfrom
feat/durable-plans

Conversation

@mukezhz

@mukezhz mukezhz commented Nov 16, 2026

Copy link
Copy Markdown
Owner

Stacked on #6.

Problem

In #6, a write that needs approval is held in a plan, but the plan only lived as long as the response that carried its ID:

  • The memory store lost it on restart, and a second replica never saw it.
  • The client could not list what was waiting, so refreshing the page lost it.
  • Expiry was 15 minutes and the client was never told; it found out from a 404.
  • There was no status or history: a plan was either there or silently gone.
  • A crash halfway through applying lost the plan after some writes had already run.

When a run failed, nothing tied its error, its logs and its plan together.

Solution

A plan is a row in a database, not a process (ADR 0009). There is no actor framework and no workflow engine.

store, _ := sqlplans.Open(ctx, db, sqlplans.SQLite) // or sqlplans.Postgres; your driver
plans := agent.NewPlans(store, agent.PlanOptions{TTL: 24 * time.Hour, OnEvent: agent.LogEvents(logger)})

_, err := agent.Run(ctx, mode, model, request, agent.Options{Runner: runner, Plans: plans, PlanOwner: user.ID})
var pending *agent.Pending // pending.ID, pending.ExpiresAt, pending.Calls

inbox, _ := plans.List(ctx, user.ID, agent.PlanPending)
plan, err := plans.Approve(ctx, mode, user.ID, id) // or Reject, Resume
  • One object is the whole approval API. agent.Plans has List (the inbox), Get, Approve, Reject and Resume.
  • States: pending → applying → applied | failed, or rejected / expired. Every change is recorded in History with its time, who made it and a note.
  • A plan applies once, even across replicas. Each update is a compare-and-set on the stored version. Eight simultaneous approvals: exactly one wins.
  • Expiry is checked whenever a plan is read, and the plan moves to expired with an event. No background job.
  • Crash safety: each call's result is recorded before the next call runs. After a crash, Resume continues from the first call with no recorded result.
  • Errors name the plan and its state, for example plan 3f2a… is already applied (by ada at …) or plan 3f2a…: call 2 of 3 (tasks.delete): …. They wrap ErrNoPlan, ErrPlanExpired or ErrPlanDecided.
  • agent.PlanStore is a four-method port. agent/sqlplans implements it for SQLite and Postgres using only database/sql, so it imports no driver. agent/plantest.Run is the contract test every store passes.
  • Observability: Options.OnEvent receives one agent.Event per step of a run or plan, each carrying the run ID. agent.LogEvents sends them to log/slog. Every error Run returns, except *Pending, is an *agent.Error with the run ID and the stage that failed. Result.RunID and Plan.RunID complete the link.
  • taskreport: plans live in the app's SQLite file. There's a new GET /api/plans and an Approvals page showing each plan's expiry and history. Approve and reject return 409 for an already-decided plan and 410 for an expired one, along with the plan as it stands.

NewMemoryPlans and ApplyPlan from #6 are replaced; neither was released.

Verification

  • make test: buf lint, go test ./..., the env check, and the consumer check (agent/sqlplans builds with CGO_ENABLED=0).
  • go test -race ./agent/... and the taskreport server tests.
  • The plantest contract on the memory store, on SQLite (including a plan surviving a reopen), and on Postgres 17 in Docker. make test-postgres now runs the Postgres plan test too.
  • Lifecycle tests: inbox, approve, a second approve refused, another owner refused, reject, expiry with a fake clock, a failed call naming its index, resume after a simulated crash, concurrent approvals, and every event carrying the run ID.
  • A bug caught by the resume test, now fixed: Approve on a plan that was already applying went through, which could have run its calls twice.
  • Live check against a running taskreport server: a plan inserted into its SQLite file was listed by GET /api/plans, approved (pending → applying → applied), and refused with 409 the second time. The log lines carried the run and plan IDs.
  • The frontend builds and typechecks. The Approvals page was not clicked through in a browser.
  • Each commit builds and passes tests on its own.

TestRunReportsWhereTheTimeWent failed once under a full parallel go test ./... and then passed 200 of 200 runs, both on this branch and on main. Its fakes are instant, and the Apple Silicon clock advances in roughly 42ns steps, so a step that fast can measure as zero. It's an existing flake and is not addressed here.

Not in this PR

  • Approval by someone other than the plan's owner.
  • An OpenTelemetry adapter package (the docs show a snippet over OnEvent).
  • Notifications beyond the plan.held event.
  • apply_plan over MCP.

agent.Plans is the approval API: List (the inbox), Get, Approve, Reject
and Resume. A plan carries its status, expiry, request, run ID, each
applied call's result and a history of every change. Decisions are a
compare-and-set on the stored version, so a plan applies once across
replicas; expiry is checked on read; applying records each result before
the next call, so a crash resumes instead of losing the plan. Errors
name the plan and its state.

agent/sqlplans stores plans in SQLite or Postgres through database/sql,
and agent/plantest is the contract every store passes.

Options.OnEvent reports every step of a run with its run ID, LogEvents
sends events to slog, and every error Run returns except *Pending is an
*agent.Error with the run ID and the failing stage.

Replaces NewMemoryPlans and ApplyPlan, which were never released.
Plans live in the app's SQLite file. The Approvals page lists every plan
from GET /api/plans with its expiry and history, and the chat shows the
same view for a plan it just held. Approve and reject answer 409 for a
decided plan and 410 for an expired one, with the plan as it stands.
Approving writes is rewritten around agent.Plans: setup, states, what is
guaranteed and the errors each situation returns. A new observability
page covers events, LogEvents, agent.Error and adapting events to
tracing. Adds ADR 0009 and the durable-plans milestone.
Base automatically changed from feat/typed-capability-sources to main November 16, 2026 06:09
@mukezhz
mukezhz merged commit 76580f7 into main Nov 16, 2026
0 of 7 checks passed
@mukezhz
mukezhz deleted the feat/durable-plans branch November 16, 2026 06:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant